QuickTime 3 Reference
Performs field operations on video data. It allows fields from two separate images, compressed in the same format, to be combined in to a new compressed frame. Typically the operation results in an image of identical quality to the source images. Fields of a single image may also be duplicated or reversed by this function.
pascal ComponentResult ImageCodecExtractAndCombineFields (
ComponentInstance ci,
long fieldFlags,
void *data1,
long dataSize1,
ImageDescriptionHandle desc1,
void *data2,
long dataSize2,
ImageDescriptionHandle desc2,
void *outputData,
long *outDataSize,
ImageDescriptionHandle descOut);
This codec routine implements the functionality of the ImageFieldSequenceExtractCombine function described in Chapter 3, "Image Compression Manager." If your codec is capable of separately compressing both fields of a video frame, you should incorporate support for this function.
Your codec must ensure that it understands the image formats specified by desc1 and desc2 parameters, as these may not be the same as the codec's native image format. The image format specified by the descOut parameter will be the same as the codec's native image format.
The component selector for this function is:
kImageCodecExtractAndCombineFieldsSelect = 0x0015
Your component receives an ImageCodecPreDecompress call before decompressing an image or sequence of frames.
pascal ComponentResult ImageCodecPreDecompress(
ComponentInstance ci,
CodecDecompressParams *params);
If your decompressor component supports scheduled asynchronous decompression operations, be sure to set the codecCanAsyncWhen flag to 1 in the flags field of your component's compressor capabilities structure. If you set codecCanAsyncWhen you must also set codecCanAsync . Codecs that support scheduled asynchronous decompression are strongly advised to also set the codecCanShieldCursor flag.
If your decompressor component uses a secondary hardware buffer for its images, be sure to set the codecHasVolatileBuffer flag to 1 in the flags field of your component's compressor capabilities structure.
If your decompressor component is used solely as a transfer codec and uses the CDCodecNewImageBufferMemory call to create an offscreen buffer that is really onscreen, your codec will need to set the codecImageBufferIsOnScreen flag to 1.
See the section "The Compressor Capability Structure" for more information about these flags.
Your component receives an ImageCodecBandDecompress call to decompress a frame.
pascal ComponentResult ImageCodecBandDecompress(
ComponentInstance ci,
CodecDecompressParams *params);
For scheduled asynchronous decompression operations, the Image Compression Manager supplies a reference to an ICMFrameTime structure in this function's decompression parameters structure parameter. The ICMFrameTime structure The Frame Time Structure contains time information governing the scheduled decompression operation, including the time at which the frame must be displayed. For synchronous or immediate asynchronous decompress operations, the frame time is set to nil .
When your component has finished the decompression operation, it must call the completion function. In the past, for asynchronous operations, your component called that function directly. For scheduled asynchronous decompression operations, your component should call the Image Compression Manager's ICMDecompressComplete function .
If your component set the codecCanAsyncWhen flag in pre-decompress but cannot support scheduled asynchronous decompression for a given frame, it must return an error code of codecCantWhenErr . If your component's queue is full, it should return an error code of codecCantQueueErr .
Empties a image decompressor component's input queue of pending scheduled frames.
pascal ComponentResult ImageCodecFlush(
ComponentInstance ci);
Your component receives the ImageCodecFlush function whenever the Image Compression Manager needs to cancel the display of all scheduled frames.
Your decompressor should empty its queue of scheduled asynchronous decompression requests. For each request, your component must call the ICMDecompressComplete function. Be sure to set the err parameter to -1, indicating that the request was canceled. Also, you must set both the codecCompletionSource and codecCompletionDest flags to 1. Only decompressor components that support scheduled asynchronous decompression receive this call.
Sets the timecode for the next frame that is to be decompressed.
pascal OSErr ImageCodecSetTimeCode (
ComponentInstance ci,
void *timeCodeFormat,
void *timeCodeTime);
Your component receives CDCodecSetTimeCode function whenever an application calls the Image Compression Manager's SetDSequenceTimeCode function. That function allows an application to set the timecode for a frame that is to be decompressed.
The timecode information you receive applies to the next frame to be decompressed and is provided to the decompressor in the CDBandDecompress function.
pascal ComponentResult ImageCodecIsImageDescriptionEquivalent (
ComponentInstance ci,
ImageDescriptionHandle newDesc,
Boolean *equivalent);
Your component receives the ImageCodecIsImageDescriptionEquivalent request whenever an application calls the Image Compression Manager's CDSequenceEquivalentImageDescription function. Implementing this function can significantly improve playback of edited video sequences using your codec. For example, if two sequences are compressed at different quality levels and are edited together they will have different image descriptions because their quality values will be different. This will force QuickTime to use two separate decompressor instances to display the images. By implementing this function your decompressor can tell QuickTime that differences in quality levels don't require separate decompressors. This saves memory and time, thus improving performance.
Requests codec-allocated memory. Some hardware codecs may have on-board memory which can be used to store compressed and/or decompressed data. ImageCodecNewMemory makes this memory available for use by clients of the codec. Some software codecs may be able to optimize thier performance by having more control over memory allocation. ImageCodecNewMemory makes this control available.
pascal ComponentResult ImageCodecNewMemory (
ComponentInstance ci,
Ptr *data,
Size dataSize,
long dataUse,
ICMMemoryDisposedUPP memoryGoneProc,
void *refCon);
Your component receives the ImageCodecNewMemory request whenever an application calls the Image Compression Manager's CDSequenceNewMemory function.
The Image Compression Manager does not currently track memory allocations. When a compressor or decompressor component instance is closed, it must ensure that all blocks allocated by that instance are disposed (and call the ICMMemoryDisposeUPP ). If your codec does not currently have free memory for compression frame data, but will soon , you can return codecMemoryFullPleaseWait to indicate this fact.
Requests the codec to allocate memory for an offscreen buffer of non-RGB pixels. This call is used to support a codec decompressing into a non-RGB buffer. The transfer codec is responsible for defining the offscreen and transferring the image from the offscreen to the destination.
pascal ComponentResult ImageCodecNewImageBufferMemory(
ComponentInstance ci,
CodecDecompressParams *params,
long flags,
ICMMemoryDisposedUPP memoryGoneProc,
void *refCon)
Your component receives the ImageCodecNewImageBufferMemory request whenever another codec has requested a non-RGB offscreen buffer of the with a type of your component's subtype. See "Accelerated Video Support" for more information.
Disposes codec-allocated memory.
pascal ComponentResult ImageCodecDisposeMemory (
ComponentInstance ci,
Ptr data);
Displays a dialog box containing codec-specific compression settings.
pascal ComponentResult ImageCodecRequestSettings (
ComponentInstance ci,
Handle settings,
Rect *rp,
ModalFilterUPP filterProc);
The ImageCodecRequestSettings function allows the display of a dialog box of additional compression settings specific to the codec. These settings are stored in a settings handle. The codec can store any data in any format it wants in the settings handle and resize it accordingly. It should store some type of tag or version information that it can use to verify that the data belongs to the codec. The codec should not dispose of the handle.
Returns the settings chosen by the user.
pascal ComponentResult ImageCodecGetSettings (
ComponentInstance ci,
Handle settings);
Sets the settings of the optional dialog box.
pascal ComponentResult ImageCodecSetSettings (
ComponentInstance ci,
Handle settings);
This routine is called when the application calls PtInDSequenceData . It returns a Boolean indicating whether or not the specified point is contained within the specified image data.
pascal ComponentResult ImageCodecHitTestData(
ComponentInstance ci,
ImageDescriptionHandle desc,
void *data,
Size dataSize,
Point where,
Boolean *hit)
The ImageCodecHitTestData function allows the calling application to perform hit testing on compressed data. The codec should set the hit parameter to true if the compressed data contains data at the point specified by the where parameter. The hit parameter should be set to false if the specified point falls within a blank portion of the image.
Your codec receives the request when an application calls the Image Compression Manager's GetCSequenceMaxCompressionSize function. The caller uses this function to determine the maximum size the data will be compressed to for a given image and set of data sources.
pascal ComponentResult ImageCodecGetMaxCompressionSizeWithSources(
ComponentInstance ci,
PixMapHandle src,
const Rect *srcRect,
short depth,
CodecQ quality,
CDSequenceDataSourcePtr sourceData,
long *size)
Your codec receives this notification that one of the data sources has changed when an application calls the Image Compression Manager's CDSequenceSetSourceData or CDSequenceChangedSourceData functions.
pascal ComponentResult ImageCodecSourceChanged(
ComponentInstance ci,
UInt32 majorSourceChangeSeed,
UInt32 minorSourceChangeSeed,
CDSequenceDataSourcePtr sourceData,
long *flagsOut;